% arara: pdflatex: { files: [latexindent]}
\subsection{Poly-switches}\label{sec:poly-switches}
	Every other field in the \texttt{modifyLineBreaks} field uses poly-switches, and can take
	one of the following%
	\announce{2017-08-21}*{blank line poly-switch} integer values:
	\index{modifying linebreaks! using poly-switches}
	\index{poly-switches!definition}
	\index{poly-switches!values}
	\index{poly-switches!off by default: set to 0}
	\begin{description}
		\item[$-1$] \emph{remove mode}: line breaks before or after the
			\emph{<part of thing>} can be removed (assuming that \texttt{preserveBlankLines} is
			set to \texttt{0});
		\item[0] \emph{off mode}: line breaks will not be modified for the
			\emph{<part of thing>} under consideration;
		\item[1] \emph{add mode}: a line break will be added before or after the
			\emph{<part of thing>} under consideration, assuming that
			there is not already a line break before or after the \emph{<part of thing>};
		\item[2] \emph{comment then add mode}: a comment symbol will be added, followed by a line break
			before or after the \emph{<part of thing>} under consideration, assuming that there is
			not already a comment and line break before or after the \emph{<part of thing>};
		\item[3] \emph{add then blank line mode}%
			\announce{2017-08-21}{blank line poly-switch}: a line break will be added before or after
			the \emph{<part of thing>} under consideration, assuming that there is not already a line
			break before or after the \emph{<part of thing>}, followed by a blank line;
		\item[4] \emph{add blank line mode}%
			\announce{2019-07-13}{blank line poly-switch}; a blank line will
			be added before or after the \emph{<part of thing>} under consideration, even if the
			\emph{<part of thing>} is already on its own line.
	\end{description}
	In the above, \emph{<part of thing>} refers to either the \emph{begin statement},
	\emph{body} or \emph{end statement} of the code blocks detailed in
	\vref{tab:code-blocks}. All poly-switches are \emph{off} by default;
	\texttt{latexindent.pl} searches first of all for per-name settings, and then followed by
	global per-thing settings.

\subsubsection{Poly-switches for environments}\label{sec:modifylinebreaks-environments}
	We start by viewing a snippet of \texttt{defaultSettings.yaml} in
	\cref{lst:environments-mlb}; note that it contains \emph{global} settings (immediately
	after the \texttt{environments} field) and that \emph{per-name} settings are also allowed
	-- in the case of \cref{lst:environments-mlb}, settings for \texttt{equation*} have been
	specified for demonstration. Note that all poly-switches are \emph{off} (set to 0) by
	default.
	\index{poly-switches!default values}
	\index{poly-switches!environment global example}
	\index{poly-switches!environment per-code block example}

	\cmhlistingsfromfile[style=modifylinebreaksEnv]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,MLB-TCB]{\texttt{environments}}{lst:environments-mlb}

	Let's begin with the simple example given in \cref{lst:env-mlb1-tex}; note that we have
	annotated key parts of the file using $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$,
	$\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$, these will be related to fields
	specified in \cref{lst:environments-mlb}.
	\index{poly-switches!visualisation: $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$, $\EndFinishesWithLineBreak$}

	\begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb1.tex}}{lst:env-mlb1-tex}
before words(*@$\BeginStartsOnOwnLine$@*) \begin{myenv}(*@$\BodyStartsOnOwnLine$@*)body of myenv(*@$\EndStartsOnOwnLine$@*)\end{myenv}(*@$\EndFinishesWithLineBreak$@*) after words
\end{cmhlistings}

	\paragraph{Adding line breaks: BeginStartsOnOwnLine and BodyStartsOnOwnLine}
		Let's explore \texttt{BeginStartsOnOwnLine} and \texttt{BodyStartsOnOwnLine} in
		\cref{lst:env-mlb1,lst:env-mlb2}, and in particular, let's allow each of them in turn to
		take a value of $1$.
		\index{modifying linebreaks! at the \emph{beginning} of a code block}
		\index{poly-switches!adding line breaks: set to 1}

		\begin{minipage}{.45\textwidth}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb1.yaml}[MLB-TCB]{\texttt{env-mlb1.yaml}}{lst:env-mlb1}
		\end{minipage}
		\hfill
		\begin{minipage}{.45\textwidth}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb2.yaml}[MLB-TCB]{\texttt{env-mlb2.yaml}}{lst:env-mlb2}
		\end{minipage}

		After running the following commands,
		\index{switches!-l demonstration}
		\index{switches!-m demonstration}
		\begin{commandshell}
latexindent.pl -m env-mlb.tex -l env-mlb1.yaml
latexindent.pl -m env-mlb.tex -l env-mlb2.yaml
\end{commandshell}
		the output is as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2} respectively.

		\begin{widepage}
			\begin{minipage}{.56\linewidth}
				\cmhlistingsfromfile{demonstrations/env-mlb-mod1.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb1}}{lst:env-mlb-mod1}
			\end{minipage}
			\hfill
			\begin{minipage}{.43\linewidth}
				\cmhlistingsfromfile{demonstrations/env-mlb-mod2.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb2}}{lst:env-mlb-mod2}
			\end{minipage}
		\end{widepage}

		There are a couple of points to note:
		\begin{itemize}
			\item in \cref{lst:env-mlb-mod1} a line break has been added at the point denoted by
			      $\BeginStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; no other line breaks have been
			      changed;
			\item in \cref{lst:env-mlb-mod2} a line break has been added at the point denoted by
			      $\BodyStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; furthermore, note that the \emph{body}
			      of \texttt{myenv} has received the appropriate (default) indentation.
		\end{itemize}

		Let's now change each of the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so
		that they are $2$ and save them into \texttt{env-mlb3.yaml} and \texttt{env-mlb4.yaml}
		respectively (see \cref{lst:env-mlb3,lst:env-mlb4}).
		\index{poly-switches!adding comments and then line breaks: set to 2}

		\begin{minipage}{.45\textwidth}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb3.yaml}[MLB-TCB]{\texttt{env-mlb3.yaml}}{lst:env-mlb3}
		\end{minipage}
		\hfill
		\begin{minipage}{.45\textwidth}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb4.yaml}[MLB-TCB]{\texttt{env-mlb4.yaml}}{lst:env-mlb4}
		\end{minipage}

		Upon running commands analogous to the above, we obtain
		\cref{lst:env-mlb-mod3,lst:env-mlb-mod4}.

		\begin{widepage}
			\begin{minipage}{.56\linewidth}
				\cmhlistingsfromfile{demonstrations/env-mlb-mod3.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb3}}{lst:env-mlb-mod3}
			\end{minipage}
			\hfill
			\begin{minipage}{.43\linewidth}
				\cmhlistingsfromfile{demonstrations/env-mlb-mod4.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb4}}{lst:env-mlb-mod4}
			\end{minipage}
		\end{widepage}

		Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but
		this time a comment symbol has been added before adding the line break; in both cases,
		trailing horizontal space has been stripped before doing so.

		Let's%
		\announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each of the \texttt{1} values in
		\cref{lst:env-mlb1,lst:env-mlb2} so that they are $3$ and save them into
		\texttt{env-mlb5.yaml} and \texttt{env-mlb6.yaml} respectively (see
		\cref{lst:env-mlb5,lst:env-mlb6}).
		\index{poly-switches!adding blank lines: set to 3}

		\begin{minipage}{.45\textwidth}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb5.yaml}[MLB-TCB]{\texttt{env-mlb5.yaml}}{lst:env-mlb5}
		\end{minipage}
		\hfill
		\begin{minipage}{.45\textwidth}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb6.yaml}[MLB-TCB]{\texttt{env-mlb6.yaml}}{lst:env-mlb6}
		\end{minipage}

		Upon running commands analogous to the above, we obtain
		\cref{lst:env-mlb-mod5,lst:env-mlb-mod6}.

		\begin{widepage}
			\begin{minipage}{.56\linewidth}
				\cmhlistingsfromfile{demonstrations/env-mlb-mod5.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb5}}{lst:env-mlb-mod5}
			\end{minipage}
			\hfill
			\begin{minipage}{.43\linewidth}
				\cmhlistingsfromfile{demonstrations/env-mlb-mod6.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb6}}{lst:env-mlb-mod6}
			\end{minipage}
		\end{widepage}

		Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but
		this time a \emph{blank line} has been added after adding the line break.

		Let's now change%
		\announce{2019-07-13}{demonstration of new blank line poly-switch} each of the \texttt{1} values in
		\cref{lst:env-mlb5,lst:env-mlb6} so that they are $4$ and save them into
		\texttt{env-beg4.yaml} and \texttt{env-body4.yaml} respectively (see
		\cref{lst:env-beg4,lst:env-body4}).
		\index{poly-switches!adding blank lines (again"!): set to 4}

		\begin{minipage}{.45\textwidth}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-beg4.yaml}[MLB-TCB]{\texttt{env-beg4.yaml}}{lst:env-beg4}
		\end{minipage}
		\hfill
		\begin{minipage}{.45\textwidth}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-body4.yaml}[MLB-TCB]{\texttt{env-body4.yaml}}{lst:env-body4}
		\end{minipage}

		We will demonstrate this poly-switch value using the code in \cref{lst:env-mlb1-text}.

		\cmhlistingsfromfile{demonstrations/env-mlb1.tex}{\texttt{env-mlb1.tex}}{lst:env-mlb1-text}

		Upon running the commands
		\index{switches!-l demonstration}
		\index{switches!-m demonstration}
		\begin{commandshell}
latexindent.pl -m env-mlb1.tex -l env-beg4.yaml
latexindent.pl -m env-mlb.1tex -l env-body4.yaml
\end{commandshell}

		then we receive the respective outputs in \cref{lst:env-mlb1-beg4,lst:env-mlb1-body4}.

		\begin{cmhtcbraster}[raster column skip=.1\linewidth]
			\cmhlistingsfromfile{demonstrations/env-mlb1-beg4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-beg4}}{lst:env-mlb1-beg4}
			\cmhlistingsfromfile{demonstrations/env-mlb1-body4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-body4}}{lst:env-mlb1-body4}
		\end{cmhtcbraster}

		We note in particular that, by design, for this value of the poly-switches:
		\begin{enumerate}
			\item in \cref{lst:env-mlb1-beg4} a blank line has been inserted before the
			      \lstinline!\begin! statement, even though the \lstinline!\begin!
			      statement was already on its own line;
			\item in \cref{lst:env-mlb1-body4} a blank line has been inserted before the beginning of the
			      \emph{body}, even though it already began on its own line.
		\end{enumerate}

	\paragraph{Adding line breaks using EndStartsOnOwnLine and EndFinishesWithLineBreak}
		Let's explore \texttt{EndStartsOnOwnLine} and \texttt{EndFinishesWithLineBreak} in
		\cref{lst:env-mlb7,lst:env-mlb8}, and in particular, let's allow each of them in turn to
		take a value of $1$.
		\index{modifying linebreaks! at the \emph{end} of a code block}
		\index{poly-switches!adding line breaks: set to 1}

		\begin{minipage}{.49\textwidth}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb7.yaml}[MLB-TCB]{\texttt{env-mlb7.yaml}}{lst:env-mlb7}
		\end{minipage}
		\hfill
		\begin{minipage}{.49\textwidth}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb8.yaml}[MLB-TCB]{\texttt{env-mlb8.yaml}}{lst:env-mlb8}
		\end{minipage}

		After running the following commands,
		\index{switches!-l demonstration}
		\index{switches!-m demonstration}
		\begin{commandshell}
latexindent.pl -m env-mlb.tex -l env-mlb7.yaml
latexindent.pl -m env-mlb.tex -l env-mlb8.yaml
\end{commandshell}
		the output is as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}.

		\begin{widepage}
			\begin{minipage}{.42\linewidth}
				\cmhlistingsfromfile{demonstrations/env-mlb-mod7.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb7}}{lst:env-mlb-mod7}
			\end{minipage}
			\hfill
			\begin{minipage}{.57\linewidth}
				\cmhlistingsfromfile{demonstrations/env-mlb-mod8.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb8}}{lst:env-mlb-mod8}
			\end{minipage}
		\end{widepage}

		There are a couple of points to note:
		\begin{itemize}
			\item in \cref{lst:env-mlb-mod7} a line break has been added at the point denoted by
			      $\EndStartsOnOwnLine$ in \vref{lst:env-mlb1-tex}; no other line breaks have been changed
			      and the \lstinline!\end{myenv}! statement has \emph{not} received indentation (as
			      intended);
			\item in \cref{lst:env-mlb-mod8} a line break has been added at the point denoted by
			      $\EndFinishesWithLineBreak$ in \vref{lst:env-mlb1-tex}.
		\end{itemize}

		Let's now change each of the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so
		that they are $2$ and save them into \texttt{env-mlb9.yaml} and \texttt{env-mlb10.yaml}
		respectively (see \cref{lst:env-mlb9,lst:env-mlb10}).
		\index{poly-switches!adding comments and then line breaks: set to 2}

		\begin{minipage}{.49\textwidth}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb9.yaml}[MLB-TCB]{\texttt{env-mlb9.yaml}}{lst:env-mlb9}
		\end{minipage}
		\hfill
		\begin{minipage}{.49\textwidth}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb10.yaml}[MLB-TCB]{\texttt{env-mlb10.yaml}}{lst:env-mlb10}
		\end{minipage}

		Upon running commands analogous to the above, we obtain
		\cref{lst:env-mlb-mod9,lst:env-mlb-mod10}.

		\begin{widepage}
			\begin{minipage}{.43\linewidth}
				\cmhlistingsfromfile{demonstrations/env-mlb-mod9.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb9}}{lst:env-mlb-mod9}
			\end{minipage}
			\hfill
			\begin{minipage}{.56\linewidth}
				\cmhlistingsfromfile{demonstrations/env-mlb-mod10.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb10}}{lst:env-mlb-mod10}
			\end{minipage}
		\end{widepage}

		Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, but
		this time a comment symbol has been added before adding the line break; in both cases,
		trailing horizontal space has been stripped before doing so.

		Let's%
		\announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each of the \texttt{1} values in
		\cref{lst:env-mlb7,lst:env-mlb8} so that they are $3$ and save them into
		\texttt{env-mlb11.yaml} and \texttt{env-mlb12.yaml} respectively (see
		\cref{lst:env-mlb11,lst:env-mlb12}).
		\index{poly-switches!adding blank lines: set to 3}

		\begin{minipage}{.49\textwidth}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb11.yaml}[MLB-TCB]{\texttt{env-mlb11.yaml}}{lst:env-mlb11}
		\end{minipage}
		\hfill
		\begin{minipage}{.49\textwidth}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb12.yaml}[MLB-TCB]{\texttt{env-mlb12.yaml}}{lst:env-mlb12}
		\end{minipage}

		Upon running commands analogous to the above, we obtain
		\cref{lst:env-mlb-mod11,lst:env-mlb-mod12}.

		\begin{widepage}
			\begin{minipage}{.42\linewidth}
				\cmhlistingsfromfile{demonstrations/env-mlb-mod11.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb11}}{lst:env-mlb-mod11}
			\end{minipage}
			\hfill
			\begin{minipage}{.57\linewidth}
				\cmhlistingsfromfile{demonstrations/env-mlb-mod12.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb12}}{lst:env-mlb-mod12}
			\end{minipage}
		\end{widepage}

		Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, and
		that a \emph{blank line} has been added after the line break.

		Let's now change%
		\announce{2019-07-13}{demonstration of new blank line poly-switch} each of the \texttt{1} values in
		\cref{lst:env-mlb11,lst:env-mlb12} so that they are $4$ and save them into
		\texttt{env-end4.yaml} and \texttt{env-end-f4.yaml} respectively (see
		\cref{lst:env-end4,lst:env-end-f4}).
		\index{poly-switches!adding blank lines (again"!): set to 4}

		\begin{minipage}{.45\textwidth}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-end4.yaml}[MLB-TCB]{\texttt{env-end4.yaml}}{lst:env-end4}
		\end{minipage}
		\hfill
		\begin{minipage}{.5\textwidth}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-end-f4.yaml}[MLB-TCB]{\texttt{env-end-f4.yaml}}{lst:env-end-f4}
		\end{minipage}

		We will demonstrate this poly-switch value using the code from \vref{lst:env-mlb1-text}.

		Upon running the commands
		\index{switches!-l demonstration}
		\index{switches!-m demonstration}
		\begin{commandshell}
latexindent.pl -m env-mlb1.tex -l env-end4.yaml
latexindent.pl -m env-mlb.1tex -l env-end-f4.yaml
\end{commandshell}

		then we receive the respective outputs in \cref{lst:env-mlb1-end4,lst:env-mlb1-end-f4}.

		\begin{cmhtcbraster}[raster column skip=.1\linewidth]
			\cmhlistingsfromfile{demonstrations/env-mlb1-end4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-end4}}{lst:env-mlb1-end4}
			\cmhlistingsfromfile{demonstrations/env-mlb1-end-f4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-end-f4}}{lst:env-mlb1-end-f4}
		\end{cmhtcbraster}

		We note in particular that, by design, for this value of the poly-switches:
		\begin{enumerate}
			\item in \cref{lst:env-mlb1-end4} a blank line has been inserted before the
			      \lstinline!\end! statement, even though the \lstinline!\end!
			      statement was already on its own line;
			\item in \cref{lst:env-mlb1-end-f4} a blank line has been inserted after the
			      \lstinline!\end! statement, even though it already began on its own line.
		\end{enumerate}

	\paragraph{poly-switches 1, 2, and 3 only add line breaks when necessary}
		If you ask \texttt{latexindent.pl} to add a line break (possibly with a comment) using a
		poly-switch value of $1$ (or $2$ or $3$), it will only do so if necessary. For example,
		if you process the file in \vref{lst:mlb2} using poly-switch values of 1, 2, or 3, it
		will be left unchanged.

		\begin{minipage}{.45\linewidth}
			\cmhlistingsfromfile{demonstrations/env-mlb2.tex}{\texttt{env-mlb2.tex}}{lst:mlb2}
		\end{minipage}
		\hfill
		\begin{minipage}{.45\linewidth}
			\cmhlistingsfromfile{demonstrations/env-mlb3.tex}{\texttt{env-mlb3.tex}}{lst:mlb3}
		\end{minipage}

		Setting the poly-switches to a value of $4$ instructs \texttt{latexindent.pl} to add a
		line break even if the \emph{<part of thing>} is already on its own line; see
		\cref{lst:env-mlb1-beg4,lst:env-mlb1-body4} and
		\cref{lst:env-mlb1-end4,lst:env-mlb1-end-f4}.

		In contrast, the output from processing the file in \cref{lst:mlb3} will vary depending
		on the poly-switches used; in \cref{lst:env-mlb3-mod2} you'll see that the comment symbol
		after the \lstinline!\begin{myenv}! has been moved to the next line, as
		\texttt{BodyStartsOnOwnLine} is set to \texttt{1}. In \cref{lst:env-mlb3-mod4} you'll see
		that the comment has been accounted for correctly because \texttt{BodyStartsOnOwnLine}
		has been set to \texttt{2}, and the comment symbol has \emph{not} been moved to its own
		line. You're encouraged to experiment with \cref{lst:mlb3} and by setting the other
		poly-switches considered so far to \texttt{2} in turn.

		\begin{cmhtcbraster}[raster column skip=.1\linewidth]
			\cmhlistingsfromfile{demonstrations/env-mlb3-mod2.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb2}}{lst:env-mlb3-mod2}
			\cmhlistingsfromfile{demonstrations/env-mlb3-mod4.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb4}}{lst:env-mlb3-mod4}
		\end{cmhtcbraster}

		The details of the discussion in this section have concerned \emph{global} poly-switches
		in the \texttt{environments} field; each switch can also be specified on a
		\emph{per-name} basis, which would take priority over the global values; with reference
		to \vref{lst:environments-mlb}, an example is shown for the \texttt{equation*}
		environment.

	\paragraph{Removing line breaks (poly-switches set to $-1$)}
		Setting poly-switches to $-1$ tells \texttt{latexindent.pl} to remove line breaks of the
		\emph{<part of the thing>}, if necessary. We will consider the example code given in
		\cref{lst:mlb4}, noting in particular the positions of the line break highlighters,
		$\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$ and
		$\EndFinishesWithLineBreak$, together with the associated YAML files in
		\crefrange{lst:env-mlb13}{lst:env-mlb16}.
		\index{poly-switches!removing line breaks: set to -1}

		\begin{minipage}{.45\linewidth}
			\begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb4.tex}}{lst:mlb4}
before words(*@$\BeginStartsOnOwnLine$@*)
\begin{myenv}(*@$\BodyStartsOnOwnLine$@*)
body of myenv(*@$\EndStartsOnOwnLine$@*)
\end{myenv}(*@$\EndFinishesWithLineBreak$@*)
after words
\end{cmhlistings}
		\end{minipage}%
		\hfill
		\begin{minipage}{.51\textwidth}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb13.yaml}[MLB-TCB]{\texttt{env-mlb13.yaml}}{lst:env-mlb13}

			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb14.yaml}[MLB-TCB]{\texttt{env-mlb14.yaml}}{lst:env-mlb14}

			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb15.yaml}[MLB-TCB]{\texttt{env-mlb15.yaml}}{lst:env-mlb15}

			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb16.yaml}[MLB-TCB]{\texttt{env-mlb16.yaml}}{lst:env-mlb16}
		\end{minipage}

		After running the commands
		\index{switches!-l demonstration}
		\index{switches!-m demonstration}
		\begin{commandshell}
latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml
latexindent.pl -m env-mlb4.tex -l env-mlb14.yaml
latexindent.pl -m env-mlb4.tex -l env-mlb15.yaml
latexindent.pl -m env-mlb4.tex -l env-mlb16.yaml
\end{commandshell}

		we obtain the respective output in \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}.

		\begin{minipage}{.45\linewidth}
			\cmhlistingsfromfile{demonstrations/env-mlb4-mod13.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb13}}{lst:env-mlb4-mod13}
		\end{minipage}
		\hfill
		\begin{minipage}{.45\linewidth}
			\cmhlistingsfromfile{demonstrations/env-mlb4-mod14.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb14}}{lst:env-mlb4-mod14}
		\end{minipage}

		\begin{minipage}{.45\linewidth}
			\cmhlistingsfromfile{demonstrations/env-mlb4-mod15.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb15}}{lst:env-mlb4-mod15}
		\end{minipage}
		\hfill
		\begin{minipage}{.45\linewidth}
			\cmhlistingsfromfile{demonstrations/env-mlb4-mod16.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb16}}{lst:env-mlb4-mod16}
		\end{minipage}

		Notice that in:
		\begin{itemize}
			\item \cref{lst:env-mlb4-mod13} the line break denoted by $\BeginStartsOnOwnLine$ in
			      \cref{lst:mlb4} has been removed;
			\item \cref{lst:env-mlb4-mod14} the line break denoted by $\BodyStartsOnOwnLine$ in
			      \cref{lst:mlb4} has been removed;
			\item \cref{lst:env-mlb4-mod15} the line break denoted by $\EndStartsOnOwnLine$ in
			      \cref{lst:mlb4} has been removed;
			\item \cref{lst:env-mlb4-mod16} the line break denoted by $\EndFinishesWithLineBreak$ in
			      \cref{lst:mlb4} has been removed.
		\end{itemize}
		We examined each of these cases separately for clarity of explanation, but you can
		combine all of the YAML settings in \crefrange{lst:env-mlb13}{lst:env-mlb16} into one
		file; alternatively, you could tell \texttt{latexindent.pl} to load them all by using the
		following command, for example
		\index{switches!-l demonstration}
		\index{switches!-m demonstration}
		\begin{widepage}
			\begin{commandshell}
latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml
\end{commandshell}
		\end{widepage}
		which gives the output in \vref{lst:env-mlb1-tex}.

	\paragraph{About trailing horizontal space}
		Recall that on \cpageref{yaml:removeTrailingWhitespace} we discussed the YAML field
		\texttt{removeTrailingWhitespace}, and that it has two (binary) switches to determine if
		horizontal space should be removed \texttt{beforeProcessing} and
		\texttt{afterProcessing}. The \texttt{beforeProcessing} is particularly relevant when
		considering the \texttt{-m} switch; let's consider the file shown in \cref{lst:mlb5},
		which highlights trailing spaces.

		\begin{cmhtcbraster}
			\begin{cmhlistings}[style=tcblatex,showspaces=true,escapeinside={(*@}{@*)}]{\texttt{env-mlb5.tex}}{lst:mlb5}
before words   (*@$\BeginStartsOnOwnLine$@*) 
\begin{myenv}           (*@$\BodyStartsOnOwnLine$@*)
body of myenv      (*@$\EndStartsOnOwnLine$@*) 
\end{myenv}     (*@$\EndFinishesWithLineBreak$@*)
after words
\end{cmhlistings}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/removeTWS-before.yaml}[yaml-TCB]{\texttt{removeTWS-before.yaml}}{lst:removeTWS-before}
		\end{cmhtcbraster}

		The output from the following commands
		\index{switches!-l demonstration}
		\index{switches!-m demonstration}
		\begin{widepage}
			\begin{commandshell}
latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml
latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml,removeTWS-before.yaml
\end{commandshell}
		\end{widepage}
		is shown, respectively, in \cref{lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS}; note
		that the trailing horizontal white space has been preserved (by default) in
		\cref{lst:env-mlb5-modAll}, while in \cref{lst:env-mlb5-modAll-remove-WS}, it has been
		removed using the switch specified in \cref{lst:removeTWS-before}.

		\begin{widepage}
			\cmhlistingsfromfile[showspaces=true]{demonstrations/env-mlb5-modAll.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}}{lst:env-mlb5-modAll}

			\cmhlistingsfromfile[showspaces=true]{demonstrations/env-mlb5-modAll-remove-WS.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16} \emph{and} \cref{lst:removeTWS-before}}{lst:env-mlb5-modAll-remove-WS}
		\end{widepage}

	\paragraph{poly-switch line break removal and blank lines}
		Now let's consider the file in \cref{lst:mlb6}, which contains blank lines.
		\index{poly-switches!blank lines}

		\begin{cmhtcbraster}
			\begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb6.tex}}{lst:mlb6}
before words(*@$\BeginStartsOnOwnLine$@*)


\begin{myenv}(*@$\BodyStartsOnOwnLine$@*)


body of myenv(*@$\EndStartsOnOwnLine$@*)


\end{myenv}(*@$\EndFinishesWithLineBreak$@*)

after words
\end{cmhlistings}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/UnpreserveBlankLines.yaml}[MLB-TCB]{\texttt{UnpreserveBlankLines.yaml}}{lst:UnpreserveBlankLines}
		\end{cmhtcbraster}

		Upon running the following commands
		\index{switches!-l demonstration}
		\index{switches!-m demonstration}
		\begin{widepage}
			\begin{commandshell}
latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml
latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml,UnpreserveBlankLines.yaml
\end{commandshell}
		\end{widepage}
		we receive the respective outputs in
		\cref{lst:env-mlb6-modAll,lst:env-mlb6-modAll-un-Preserve-Blank-Lines}. In
		\cref{lst:env-mlb6-modAll} we see that the multiple blank lines have each been condensed
		into one blank line, but that blank lines have \emph{not} been removed by the
		poly-switches -- this is because, by default, \texttt{preserveBlankLines} is set to
		\texttt{1}. By contrast, in \cref{lst:env-mlb6-modAll-un-Preserve-Blank-Lines}, we have
		allowed the poly-switches to remove blank lines because, in
		\cref{lst:UnpreserveBlankLines}, we have set \texttt{preserveBlankLines} to \texttt{0}.

		\begin{cmhtcbraster}[ raster left skip=-3.5cm,
				raster right skip=-2cm,
				raster force size=false,
				raster column 1/.style={add to width=-.2\textwidth},
				raster column 2/.style={add to width=.2\textwidth},
				raster column skip=.06\linewidth]
			\cmhlistingsfromfile{demonstrations/env-mlb6-modAll.tex}{\texttt{env-mlb6.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}}{lst:env-mlb6-modAll}
			\cmhlistingsfromfile{demonstrations/env-mlb6-modAll-un-Preserve-Blank-Lines.tex}{\texttt{env-mlb6.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16} \emph{and} \cref{lst:UnpreserveBlankLines}}{lst:env-mlb6-modAll-un-Preserve-Blank-Lines}
		\end{cmhtcbraster}

		We can explore this further using the blank-line poly-switch value of $3$; let's use the
		file given in \cref{lst:env-mlb7-tex}.

		\cmhlistingsfromfile{demonstrations/env-mlb7.tex}{\texttt{env-mlb7.tex}}{lst:env-mlb7-tex}

		Upon running the following commands
		\index{switches!-l demonstration}
		\index{switches!-m demonstration}
		\begin{commandshell}
latexindent.pl -m env-mlb7.tex -l env-mlb12.yaml,env-mlb13.yaml
latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankLines.yaml
\end{commandshell}
		we receive the outputs given in \cref{lst:env-mlb7-preserve,lst:env-mlb7-no-preserve}.

		\cmhlistingsfromfile{demonstrations/env-mlb7-preserve.tex}{\texttt{env-mlb7-preserve.tex}}{lst:env-mlb7-preserve}
		\cmhlistingsfromfile{demonstrations/env-mlb7-no-preserve.tex}{\texttt{env-mlb7-no-preserve.tex}}{lst:env-mlb7-no-preserve}

		Notice that in:
		\begin{itemize}
			\item \cref{lst:env-mlb7-preserve} that \lstinline!\end{one}! has added a blank line,
			      because of the value of \texttt{EndFinishesWithLineBreak} in \vref{lst:env-mlb12}, and
			      even though the line break ahead of \lstinline!\begin{two}! should have been removed
			      (because of \texttt{BeginStartsOnOwnLine} in \vref{lst:env-mlb13}), the blank line has
			      been preserved by default;
			\item \cref{lst:env-mlb7-no-preserve}, by contrast, has had the additional line-break removed,
			      because of the settings in \cref{lst:UnpreserveBlankLines}.
		\end{itemize}

\subsubsection{Poly-switches for double back slash}\label{subsec:dbs}
	With reference to \texttt{lookForAlignDelims} (see
	\vref{lst:aligndelims:basic})%
	\announce{2019-07-13}{poly-switch for double back slash} you can specify poly-switches to
	dictate the line-break behaviour of double back slashes in environments
	(\vref{lst:tabularafter:basic}), commands (\vref{lst:matrixafter}), or special code
	blocks (\vref{lst:specialafter}). Note that for these poly-switches to take effect, the
	name of the code block must necessarily be specified within \texttt{lookForAlignDelims}
	(\vref{lst:aligndelims:basic}); we will demonstrate this in what follows.
	\index{delimiters!poly-switches for double back slash}
	\index{modifying linebreaks! surrounding double back slash}
	\index{poly-switches!for double back slash (delimiters)}

	Consider the code given in \cref{lst:dbs-demo}.
	\begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{tabular3.tex}}{lst:dbs-demo}
\begin{tabular}{cc}
 1 & 2 (*@$\ElseStartsOnOwnLine$@*)\\(*@$\ElseFinishesWithLineBreak$@*) 3 & 4 (*@$\ElseStartsOnOwnLine$@*)\\(*@$\ElseFinishesWithLineBreak$@*)
\end{tabular}
\end{cmhlistings}
	Referencing \cref{lst:dbs-demo}:
	\begin{itemize}
		\item \texttt{DBS} stands for \emph{double back slash};
		\item line breaks ahead of the double back slash are annotated by $\ElseStartsOnOwnLine$, and
		      are controlled by \texttt{DBSStartsOnOwnLine};
		\item line breaks after the double back slash are annotated by $\ElseFinishesWithLineBreak$,
		      and are controlled by \texttt{DBSFinishesWithLineBreak}.
	\end{itemize}

	Let's explore each of these in turn.

	\paragraph{Double back slash starts on own line}
		We explore \texttt{DBSStartsOnOwnLine} ($\ElseStartsOnOwnLine$ in \cref{lst:dbs-demo});
		starting with the code in \cref{lst:dbs-demo}, together with the YAML files given in
		\cref{lst:DBS1} and \cref{lst:DBS2} and running the following commands
		\index{switches!-l demonstration}
		\index{switches!-m demonstration}
		\begin{commandshell}
latexindent.pl -m tabular3.tex -l DBS1.yaml
latexindent.pl -m tabular3.tex -l DBS2.yaml
\end{commandshell}
		then we receive the respective output given in \cref{lst:tabular3-DBS1} and
		\cref{lst:tabular3-DBS2}.

		\begin{cmhtcbraster}[raster column skip=.01\linewidth]
			\cmhlistingsfromfile{demonstrations/tabular3-mod1.tex}{\texttt{tabular3.tex} using \cref{lst:DBS1}}{lst:tabular3-DBS1}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS1.yaml}[MLB-TCB]{\texttt{DBS1.yaml}}{lst:DBS1}
		\end{cmhtcbraster}

		\begin{cmhtcbraster}[raster column skip=.01\linewidth]
			\cmhlistingsfromfile{demonstrations/tabular3-mod2.tex}{\texttt{tabular3.tex} using \cref{lst:DBS2}}{lst:tabular3-DBS2}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS2.yaml}[MLB-TCB]{\texttt{DBS2.yaml}}{lst:DBS2}
		\end{cmhtcbraster}

		We note that
		\begin{itemize}
			\item \cref{lst:DBS1} specifies \texttt{DBSStartsOnOwnLine} for
			      \emph{every} environment (that is within \texttt{lookForAlignDelims},
			      \vref{lst:aligndelims:advanced});
			      the double back slashes from \cref{lst:dbs-demo} have been moved to their own line in
			      \cref{lst:tabular3-DBS1};
			\item \cref{lst:DBS2} specifies \texttt{DBSStartsOnOwnLine} on a
			      \emph{per-name} basis for \texttt{tabular} (that is within \texttt{lookForAlignDelims},
			      \vref{lst:aligndelims:advanced});
			      the double back slashes from \cref{lst:dbs-demo} have been moved to their own line in
			      \cref{lst:tabular3-DBS2}, having added comment symbols before moving them.
		\end{itemize}

	\paragraph{Double back slash finishes with line break}
		Let's now explore \texttt{DBSFinishesWithLineBreak} ($\ElseFinishesWithLineBreak$ in
		\cref{lst:dbs-demo}); starting with the code in \cref{lst:dbs-demo}, together with the
		YAML files given in \cref{lst:DBS3} and \cref{lst:DBS4} and running the following
		commands
		\index{poly-switches!for double back slash (delimiters)}
		\index{switches!-l demonstration}
		\index{switches!-m demonstration}
		\begin{commandshell}
latexindent.pl -m tabular3.tex -l DBS3.yaml
latexindent.pl -m tabular3.tex -l DBS4.yaml
\end{commandshell}
		then we receive the respective output given in \cref{lst:tabular3-DBS3} and
		\cref{lst:tabular3-DBS4}.

		\begin{cmhtcbraster}[raster column skip=.01\linewidth]
			\cmhlistingsfromfile{demonstrations/tabular3-mod3.tex}{\texttt{tabular3.tex} using \cref{lst:DBS3}}{lst:tabular3-DBS3}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS3.yaml}[MLB-TCB]{\texttt{DBS3.yaml}}{lst:DBS3}
		\end{cmhtcbraster}

		\begin{cmhtcbraster}[raster column skip=.01\linewidth]
			\cmhlistingsfromfile{demonstrations/tabular3-mod4.tex}{\texttt{tabular3.tex} using \cref{lst:DBS4}}{lst:tabular3-DBS4}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS4.yaml}[MLB-TCB]{\texttt{DBS4.yaml}}{lst:DBS4}
		\end{cmhtcbraster}

		We note that
		\begin{itemize}
			\item \cref{lst:DBS3} specifies \texttt{DBSFinishesWithLineBreak} for
			      \emph{every} environment (that is within \texttt{lookForAlignDelims},
			      \vref{lst:aligndelims:advanced});
			      the code following the double back slashes from \cref{lst:dbs-demo} has been moved to
			      their own line in \cref{lst:tabular3-DBS3};
			\item \cref{lst:DBS4} specifies \texttt{DBSFinishesWithLineBreak} on a
			      \emph{per-name} basis for \texttt{tabular} (that is within \texttt{lookForAlignDelims},
			      \vref{lst:aligndelims:advanced});
			      the first double back slashes from \cref{lst:dbs-demo} have moved code following them to
			      their own line in \cref{lst:tabular3-DBS4}, having added comment symbols before moving
			      them; the final double back slashes have \emph{not} added a line break as they are at the
			      end of the body within the code block.
		\end{itemize}

	\paragraph{Double back slash poly-switches for specialBeginEnd}
		Let's explore the double back slash poly-switches for code blocks within
		\texttt{specialBeginEnd} code blocks (\vref{lst:specialBeginEnd}); we begin with the code
		within \cref{lst:special4}.
		\index{specialBeginEnd!double backslash poly-switch demonstration}
		\index{poly-switches!double backslash}
		\index{poly-switches!for double back slash (delimiters)}
		\index{specialBeginEnd!lookForAlignDelims}
		\index{delimiters}
		\index{linebreaks!summary of poly-switches}

		\cmhlistingsfromfile{demonstrations/special4.tex}{\texttt{special4.tex}}{lst:special4}

		Upon using the YAML settings in \cref{lst:DBS5}, and running the command
		\index{switches!-l demonstration}
		\index{switches!-m demonstration}
		\begin{commandshell}
latexindent.pl -m special4.tex -l DBS5.yaml
\end{commandshell}
		then we receive the output given in \cref{lst:special4-DBS5}.
		\index{delimiters!with specialBeginEnd and the -m switch}

		\begin{cmhtcbraster}[
				raster force size=false,
				raster column 1/.style={add to width=-.1\textwidth},
				raster column skip=.06\linewidth]
			\cmhlistingsfromfile{demonstrations/special4-mod5.tex}{\texttt{special4.tex} using \cref{lst:DBS5}}{lst:special4-DBS5}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS5.yaml}[MLB-TCB,width=0.6\textwidth]{\texttt{DBS5.yaml}}{lst:DBS5}
		\end{cmhtcbraster}

		There are a few things to note:
		\begin{itemize}
			\item in \cref{lst:DBS5} we have specified \texttt{cmhMath} within \texttt{lookForAlignDelims};
			      without this, the double back slash poly-switches would be ignored for this code block;
			\item the \texttt{DBSFinishesWithLineBreak} poly-switch has controlled the line breaks
			      following the double back slashes;
			\item the \texttt{SpecialEndStartsOnOwnLine} poly-switch has controlled the addition of a
			      comment symbol, followed by a line break, as it is set to a value of 2.
		\end{itemize}

	\paragraph{Double back slash poly-switches for optional and mandatory arguments}
		For clarity, we provide a demonstration of controlling the double back slash
		poly-switches for optional and mandatory arguments. We begin with the code in
		\cref{lst:mycommand2}.
		\index{poly-switches!for double back slash (delimiters)}

		\cmhlistingsfromfile{demonstrations/mycommand2.tex}{\texttt{mycommand2.tex}}{lst:mycommand2}

		Upon using the YAML settings in \cref{lst:DBS6,lst:DBS7}, and running the command
		\index{switches!-l demonstration}
		\index{switches!-m demonstration}
		\begin{commandshell}
latexindent.pl -m mycommand2.tex -l DBS6.yaml
latexindent.pl -m mycommand2.tex -l DBS7.yaml
\end{commandshell}
		then we receive the output given in \cref{lst:mycommand2-DBS6,lst:mycommand2-DBS7}.

		\begin{cmhtcbraster}[
				raster force size=false,
				raster column 1/.style={add to width=-.1\textwidth},
				raster column skip=.03\linewidth]
			\cmhlistingsfromfile{demonstrations/mycommand2-mod6.tex}{\texttt{mycommand2.tex} using \cref{lst:DBS6}}{lst:mycommand2-DBS6}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS6.yaml}[MLB-TCB,width=0.6\textwidth]{\texttt{DBS6.yaml}}{lst:DBS6}
		\end{cmhtcbraster}

		\begin{cmhtcbraster}[
				raster force size=false,
				raster column 1/.style={add to width=-.1\textwidth},
				raster column skip=.03\linewidth]
			\cmhlistingsfromfile{demonstrations/mycommand2-mod7.tex}{\texttt{mycommand2.tex} using \cref{lst:DBS7}}{lst:mycommand2-DBS7}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS7.yaml}[MLB-TCB,width=0.6\textwidth]{\texttt{DBS7.yaml}}{lst:DBS7}
		\end{cmhtcbraster}

	\paragraph{Double back slash optional square brackets}
		The pattern matching for the double back slash will also, optionally, allow trailing
		square brackets that contain a measurement of vertical spacing, for example
		\lstinline!\\[3pt]!.
		\index{poly-switches!for double back slash (delimiters)}

		For example, beginning with the code in \cref{lst:pmatrix3}

		\cmhlistingsfromfile{demonstrations/pmatrix3.tex}{\texttt{pmatrix3.tex}}{lst:pmatrix3}

		and running the following command, using \cref{lst:DBS3},
		\index{switches!-l demonstration}
		\index{switches!-m demonstration}
		\begin{commandshell}
latexindent.pl -m pmatrix3.tex -l DBS3.yaml
\end{commandshell}
		then we receive the output given in \cref{lst:pmatrix3-DBS3}.

		\cmhlistingsfromfile{demonstrations/pmatrix3-mod3.tex}{\texttt{pmatrix3.tex} using \cref{lst:DBS3}}{lst:pmatrix3-DBS3}

		You can customise the pattern for the double back slash by exploring the \emph{fine
			tuning} field detailed in \vref{lst:fineTuning}.

\subsubsection{Poly-switches for other code blocks}
	Rather than repeat the examples shown for the environment code blocks (in
	\vref{sec:modifylinebreaks-environments}), we choose to detail the poly-switches for all
	other code blocks in \cref{tab:poly-switch-mapping}; note that each and every one of
	these poly-switches is \emph{off by default}, i.e, set to \texttt{0}.

	Note also that, by design, line breaks involving, \texttt{filecontents} and
	`comment-marked' code blocks (\vref{lst:alignmentmarkup}) can \emph{not} be modified
	using \texttt{latexindent.pl}.%
	\announce{2019-05-05}*{verbatim poly-switch} However, there are two poly-switches
	available for \texttt{verbatim} code blocks: environments
	(\vref{lst:verbatimEnvironments}), commands (\vref{lst:verbatimCommands}) and
	\texttt{specialBeginEnd} (\vref{lst:special-verb1-yaml}).
	\index{specialBeginEnd!poly-switch summary}
	\index{verbatim!poly-switch summary}
	\index{poly-switches!summary of all poly-switches}

	\clearpage
	\begin{longtable}{llll}
		\caption{Poly-switch mappings for all code-block types}\label{tab:poly-switch-mapping}                                                                                                                                                   \\
		\toprule
		Code block                                             & Sample                                                            & \multicolumn{2}{c}{Poly-switch mapping}                                                                     \\
		\midrule
		environment                                            & \verb!before words!$\BeginStartsOnOwnLine$                        & $\BeginStartsOnOwnLine$                 & BeginStartsOnOwnLine                                              \\
		                                                       & \verb!\begin{myenv}!$\BodyStartsOnOwnLine$                        & $\BodyStartsOnOwnLine$                  & BodyStartsOnOwnLine                                               \\
		                                                       & \verb!body of myenv!$\EndStartsOnOwnLine$                         & $\EndStartsOnOwnLine$                   & EndStartsOnOwnLine                                                \\
		                                                       & \verb!\end{myenv}!$\EndFinishesWithLineBreak$                     & $\EndFinishesWithLineBreak$             & EndFinishesWithLineBreak                                          \\
		                                                       & \verb!after words!                                                &                                         &                                                                   \\
		\cmidrule{2-4}
		ifelsefi                                               & \verb!before words!$\BeginStartsOnOwnLine$                        & $\BeginStartsOnOwnLine$                 & IfStartsOnOwnLine                                                 \\
		                                                       & \verb!\if...!$\BodyStartsOnOwnLine$                               & $\BodyStartsOnOwnLine$                  & BodyStartsOnOwnLine                                               \\
		                                                       & \verb!body of if/or statement!$\OrStartsOnOwnLine$                & $\OrStartsOnOwnLine$                    & OrStartsOnOwnLine                                                 %
		\announce{2018-04-27}{new ifElseFi code block poly-switches}                                                                                                                                                                             \\
		                                                       & \verb!\or!$\OrFinishesWithLineBreak$                              & $\OrFinishesWithLineBreak$              & OrFinishesWithLineBreak                                           \\
		                                                       & \verb!body of if/or statement!$\ElseStartsOnOwnLine$              & $\ElseStartsOnOwnLine$                  & ElseStartsOnOwnLine                                               \\
		                                                       & \verb!\else!$\ElseFinishesWithLineBreak$                          & $\ElseFinishesWithLineBreak$            & ElseFinishesWithLineBreak                                         \\
		                                                       & \verb!body of else statement!$\EndStartsOnOwnLine$                & $\EndStartsOnOwnLine$                   & FiStartsOnOwnLine                                                 \\
		                                                       & \verb!\fi!$\EndFinishesWithLineBreak$                             & $\EndFinishesWithLineBreak$             & FiFinishesWithLineBreak                                           \\
		                                                       & \verb!after words!                                                &                                         &                                                                   \\
		\cmidrule{2-4}
		optionalArguments                                      & \verb!...!$\BeginStartsOnOwnLine$                                 & $\BeginStartsOnOwnLine$                 & LSqBStartsOnOwnLine\footnote{LSqB stands for Left Square Bracket} \\
		                                                       & \verb![!$\BodyStartsOnOwnLine$                                    & $\BodyStartsOnOwnLine$                  & OptArgBodyStartsOnOwnLine                                         \\
		\announce{2019-07-13}{new comma-related poly-switches} & \verb!value before comma!$\ElseStartsOnOwnLine$,                  & $\ElseStartsOnOwnLine$                  & CommaStartsOnOwnLine                                              \\
		                                                       & $\ElseFinishesWithLineBreak$                                      & $\ElseFinishesWithLineBreak$            & CommaFinishesWithLineBreak                                        \\
		                                                       & \verb!end of body of opt arg!$\EndStartsOnOwnLine$                & $\EndStartsOnOwnLine$                   & RSqBStartsOnOwnLine                                               \\
		                                                       & \verb!]!$\EndFinishesWithLineBreak$                               & $\EndFinishesWithLineBreak$             & RSqBFinishesWithLineBreak                                         \\
		                                                       & \verb!...!                                                        &                                         &                                                                   \\
		\cmidrule{2-4}
		mandatoryArguments                                     & \verb!...!$\BeginStartsOnOwnLine$                                 & $\BeginStartsOnOwnLine$                 & LCuBStartsOnOwnLine\footnote{LCuB stands for Left Curly Brace}    \\
		                                                       & \verb!{!$\BodyStartsOnOwnLine$                                    & $\BodyStartsOnOwnLine$                  & MandArgBodyStartsOnOwnLine                                        \\
		\announce{2019-07-13}{new comma-related poly-switches} & \verb!value before comma!$\ElseStartsOnOwnLine$,                  & $\ElseStartsOnOwnLine$                  & CommaStartsOnOwnLine                                              \\
		                                                       & $\ElseFinishesWithLineBreak$                                      & $\ElseFinishesWithLineBreak$            & CommaFinishesWithLineBreak                                        \\
		                                                       & \verb!end of body of mand arg!$\EndStartsOnOwnLine$               & $\EndStartsOnOwnLine$                   & RCuBStartsOnOwnLine                                               \\
		                                                       & \verb!}!$\EndFinishesWithLineBreak$                               & $\EndFinishesWithLineBreak$             & RCuBFinishesWithLineBreak                                         \\
		                                                       & \verb!...!                                                        &                                         &                                                                   \\
		\cmidrule{2-4}
		commands                                               & \verb!before words!$\BeginStartsOnOwnLine$                        & $\BeginStartsOnOwnLine$                 & CommandStartsOnOwnLine                                            \\
		                                                       & \verb!\mycommand!$\BodyStartsOnOwnLine$                           & $\BodyStartsOnOwnLine$                  & CommandNameFinishesWithLineBreak                                  \\
		                                                       & $\langle$\itshape{arguments}$\rangle$                             &                                         &                                                                   \\
		\cmidrule{2-4}
		namedGroupingBracesBrackets                            & before words$\BeginStartsOnOwnLine$                               & $\BeginStartsOnOwnLine$                 & NameStartsOnOwnLine                                               \\
		                                                       & myname$\BodyStartsOnOwnLine$                                      & $\BodyStartsOnOwnLine$                  & NameFinishesWithLineBreak                                         \\
		                                                       & $\langle$\itshape{braces/brackets}$\rangle$                       &                                         &                                                                   \\
		\cmidrule{2-4}
		keyEqualsValuesBraces\newline Brackets                 & before words$\BeginStartsOnOwnLine$                               & $\BeginStartsOnOwnLine$                 & KeyStartsOnOwnLine                                                \\
		                                                       & key$\EqualsStartsOnOwnLine$=$\BodyStartsOnOwnLine$                & $\EqualsStartsOnOwnLine$                & EqualsStartsOnOwnLine                                             \\
		                                                       & $\langle$\itshape{braces/brackets}$\rangle$                       & $\BodyStartsOnOwnLine$                  & EqualsFinishesWithLineBreak                                       \\
		\cmidrule{2-4}
		items                                                  & before words$\BeginStartsOnOwnLine$                               & $\BeginStartsOnOwnLine$                 & ItemStartsOnOwnLine                                               \\
		                                                       & \verb!\item!$\BodyStartsOnOwnLine$                                & $\BodyStartsOnOwnLine$                  & ItemFinishesWithLineBreak                                         \\
		                                                       & \verb!...!                                                        &                                         &                                                                   \\
		\cmidrule{2-4}
		specialBeginEnd                                        & before words$\BeginStartsOnOwnLine$                               & $\BeginStartsOnOwnLine$                 & SpecialBeginStartsOnOwnLine                                       \\
		                                                       & \verb!\[!$\BodyStartsOnOwnLine$                                   & $\BodyStartsOnOwnLine$                  & SpecialBodyStartsOnOwnLine                                        \\
		                                                       & \verb!body of special/middle!$\ElseStartsOnOwnLine$               & $\ElseStartsOnOwnLine$                  & SpecialMiddleStartsOnOwnLine                                      %
		\announce{2018-04-27}{new special code block poly-switches}                                                                                                                                                                              \\
		                                                       & \verb!\middle!$\ElseFinishesWithLineBreak$                        & $\ElseFinishesWithLineBreak$            & SpecialMiddleFinishesWithLineBreak                                \\
		                                                       & body of special/middle $\EndStartsOnOwnLine$                      & $\EndStartsOnOwnLine$                   & SpecialEndStartsOnOwnLine                                         \\
		                                                       & \verb!\]!$\EndFinishesWithLineBreak$                              & $\EndFinishesWithLineBreak$             & SpecialEndFinishesWithLineBreak                                   \\
		                                                       & after words                                                       &                                         &                                                                   \\
		\cmidrule{2-4}
		verbatim                                               & before words$\BeginStartsOnOwnLine$\verb!\begin{verbatim}!        & $\BeginStartsOnOwnLine$                 & VerbatimBeginStartsOnOwnLine                                      \\
		\announce{2019-05-05}{verbatim poly-switches}          & body of verbatim \verb!\end{verbatim}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$             & VerbatimEndFinishesWithLineBreak                                  \\
		                                                       & after words                                                       &                                         &                                                                   \\
		\bottomrule
	\end{longtable}
\subsubsection{Partnering BodyStartsOnOwnLine with argument-based poly-switches}
	Some poly-switches need to be partnered together; in particular, when line breaks
	involving the \emph{first} argument of a code block need to be accounted for using both
	\texttt{BodyStartsOnOwnLine} (or its equivalent, see \vref{tab:poly-switch-mapping}) and
	\texttt{LCuBStartsOnOwnLine} for mandatory arguments, and \texttt{LSqBStartsOnOwnLine}
	for optional arguments.
	\index{poly-switches!conflicting partnering}

	Let's begin with the code in \cref{lst:mycommand1} and the YAML settings in
	\cref{lst:mycom-mlb1}; with reference to \vref{tab:poly-switch-mapping}, the key
	\texttt{CommandNameFinishesWithLineBreak} is an alias for \texttt{BodyStartsOnOwnLine}.

	\cmhlistingsfromfile{demonstrations/mycommand1.tex}{\texttt{mycommand1.tex}}{lst:mycommand1}

	Upon running the command
	\index{switches!-l demonstration}
	\index{switches!-m demonstration}
	\begin{commandshell}
latexindent.pl -m -l=mycom-mlb1.yaml mycommand1.tex
\end{commandshell}
	we obtain \cref{lst:mycommand1-mlb1}; note that the \emph{second} mandatory argument
	beginning brace \lstinline!{! has had its leading line break removed, but that the
	\emph{first} brace has not.

	\begin{cmhtcbraster}[
			raster force size=false,
			raster column 1/.style={add to width=-1cm},
		]
		\cmhlistingsfromfile{demonstrations/mycommand1-mlb1.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb1}}{lst:mycommand1-mlb1}
		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb1.yaml}[MLB-TCB,width=.6\textwidth]{\texttt{mycom-mlb1.yaml}}{lst:mycom-mlb1}
	\end{cmhtcbraster}

	Now let's change the YAML file so that it is as in \cref{lst:mycom-mlb2}; upon running
	the analogous command to that given above, we obtain \cref{lst:mycommand1-mlb2}; both
	beginning braces \lstinline!{! have had their leading line breaks removed.

	\begin{cmhtcbraster}[
			raster force size=false,
			raster column 1/.style={add to width=-1cm},
		]
		\cmhlistingsfromfile{demonstrations/mycommand1-mlb2.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb2}}{lst:mycommand1-mlb2}
		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb2.yaml}[MLB-TCB,width=.6\textwidth]{\texttt{mycom-mlb2.yaml}}{lst:mycom-mlb2}
	\end{cmhtcbraster}

	Now let's change the YAML file so that it is as in \cref{lst:mycom-mlb3}; upon running
	the analogous command to that given above, we obtain \cref{lst:mycommand1-mlb3}.

	\begin{cmhtcbraster}[
			raster force size=false,
			raster column 1/.style={add to width=-1cm},
		]
		\cmhlistingsfromfile{demonstrations/mycommand1-mlb3.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb3}}{lst:mycommand1-mlb3}
		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb3.yaml}[MLB-TCB,width=.6\textwidth]{\texttt{mycom-mlb3.yaml}}{lst:mycom-mlb3}
	\end{cmhtcbraster}

\subsubsection{Conflicting poly-switches: sequential code blocks}
	It is very easy to have conflicting poly-switches; if we use the example from
	\vref{lst:mycommand1}, and consider the YAML settings given in \cref{lst:mycom-mlb4}. The
	output from running
	\index{poly-switches!conflicting switches}
	\index{switches!-l demonstration}
	\index{switches!-m demonstration}
	\begin{commandshell}
latexindent.pl -m -l=mycom-mlb4.yaml mycommand1.tex
\end{commandshell}
	is given in \cref{lst:mycom-mlb4}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/mycommand1-mlb4.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb4}}{lst:mycommand1-mlb4}
		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb4.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb4.yaml}}{lst:mycom-mlb4}
	\end{cmhtcbraster}

	Studying \cref{lst:mycom-mlb4}, we see that the two poly-switches are at opposition with
	one another:
	\begin{itemize}
		\item on the one hand, \texttt{LCuBStartsOnOwnLine} should \emph{not} start on its own line (as
		      poly-switch is set to $-1$);
		\item on the other hand, \texttt{RCuBFinishesWithLineBreak} \emph{should} finish with a line
		      break.
	\end{itemize}
	So, which should win the conflict? As demonstrated in \cref{lst:mycommand1-mlb4}, it is
	clear that \texttt{LCuBStartsOnOwnLine} won this conflict, and the reason is that
	\emph{the second argument was processed after the first} -- in general, the most
	recently-processed code block and associated poly-switch takes priority.

	We can explore this further by considering the YAML settings in \cref{lst:mycom-mlb5};
	upon running the command
	\index{switches!-l demonstration}
	\index{switches!-m demonstration}
	\begin{commandshell}
latexindent.pl -m -l=mycom-mlb5.yaml mycommand1.tex
\end{commandshell}
	we obtain the output given in \cref{lst:mycommand1-mlb5}.

	\begin{cmhtcbraster}[raster column skip=.1\linewidth]
		\cmhlistingsfromfile{demonstrations/mycommand1-mlb5.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb5}}{lst:mycommand1-mlb5}
		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb5.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb5.yaml}}{lst:mycom-mlb5}
	\end{cmhtcbraster}

	As previously, the most-recently-processed code block takes priority -- as before, the
	second (i.e, \emph{last}) argument. Exploring this further, we consider the YAML settings
	in \cref{lst:mycom-mlb6}, which give associated output in \cref{lst:mycommand1-mlb6}.

	\begin{cmhtcbraster}[raster column skip=.1\linewidth]
		\cmhlistingsfromfile{demonstrations/mycommand1-mlb6.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb6}}{lst:mycommand1-mlb6}
		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb6.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb6.yaml}}{lst:mycom-mlb6}
	\end{cmhtcbraster}

	Note that a \lstinline!%! \emph{has} been added to the trailing first
	\lstinline!}!; this is because:
	\begin{itemize}
		\item while processing the \emph{first} argument, the trailing line break has been removed
		      (\texttt{RCuBFinishesWithLineBreak} set to $-1$);
		\item while processing the \emph{second} argument, \texttt{latexindent.pl} finds that it does
		      \emph{not} begin on its own line, and so because \texttt{LCuBStartsOnOwnLine} is set to
		      $2$, it adds a comment, followed by a line break.
	\end{itemize}

\subsubsection{Conflicting poly-switches: nested code blocks}
	Now let's consider an example when nested code blocks have conflicting poly-switches;
	we'll use the code in \cref{lst:nested-env}, noting that it contains nested environments.
	\index{poly-switches!conflicting switches}

	\cmhlistingsfromfile{demonstrations/nested-env.tex}{\texttt{nested-env.tex}}{lst:nested-env}

	Let's use the YAML settings given in \cref{lst:nested-env-mlb1-yaml}, which upon running
	the command
	\index{switches!-l demonstration}
	\index{switches!-m demonstration}
	\begin{commandshell}
latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex
\end{commandshell}
	gives the output in \cref{lst:nested-env-mlb1}.

	\begin{cmhtcbraster}[raster column skip=.05\linewidth]
		\cmhlistingsfromfile{demonstrations/nested-env-mlb1.tex}{\texttt{nested-env.tex} using \cref{lst:nested-env-mlb1-yaml}}{lst:nested-env-mlb1}
		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/nested-env-mlb1.yaml}[MLB-TCB,width=\linewidth]{\texttt{nested-env-mlb1.yaml}}{lst:nested-env-mlb1-yaml}
	\end{cmhtcbraster}

	In \cref{lst:nested-env-mlb1}, let's first of all note that both environments have
	received the appropriate (default) indentation; secondly, note that the poly-switch
	\texttt{EndStartsOnOwnLine} appears to have won the conflict, as \lstinline!\end{one}!
	has had its leading line break removed.

	To understand it, let's talk about the three basic phases \label{page:phases}of
	\texttt{latexindent.pl}:
	\begin{enumerate}
		\item Phase 1: packing, in which code blocks are replaced with unique ids, working from
		      \emph{the inside to the outside}, and then sequentially -- for example, in
		      \cref{lst:nested-env}, the \texttt{two} environment is found \emph{before} the
		      \texttt{one} environment; if the -m switch is active, then during this phase:
		      \begin{itemize}
			      \item line breaks at the beginning of the \texttt{body} can be added (if
			            \texttt{BodyStartsOnOwnLine} is $1$ or $2$) or removed (if \texttt{BodyStartsOnOwnLine}
			            is $-1$);
			      \item line breaks at the end of the body can be added (if \texttt{EndStartsOnOwnLine} is $1$ or
			            $2$) or removed (if \texttt{EndStartsOnOwnLine} is $-1$);
			      \item line breaks after the end statement can be added (if \texttt{EndFinishesWithLineBreak} is
			            $1$ or $2$).
		      \end{itemize}
		\item Phase 2: indentation, in which white space is added to the begin, body, and end
		      statements;
		\item Phase 3: unpacking, in which unique ids are replaced by their \emph{indented} code
		      blocks; if the -m switch is active, then during this phase,
		      \begin{itemize}
			      \item line breaks before \texttt{begin} statements can be added or removed (depending upon
			            \texttt{BeginStartsOnOwnLine});
			      \item line breaks after \emph{end} statements can be removed but \emph{NOT} added (see
			            \texttt{EndFinishesWithLineBreak}).
		      \end{itemize}
	\end{enumerate}

	With reference to \cref{lst:nested-env-mlb1}, this means that during Phase 1:
	\begin{itemize}
		\item the \texttt{two} environment is found first, and the line break ahead of the
		      \lstinline!\end{two}! statement is removed because \texttt{EndStartsOnOwnLine} is set to
		      $-1$. Importantly, because, \emph{at this stage},
		      \lstinline!\end{two}! \emph{does} finish with a line break,
		      \texttt{EndFinishesWithLineBreak} causes no action.
		\item next, the \texttt{one} environment is found; the line break ahead of
		      \lstinline!\end{one}! is removed because \texttt{EndStartsOnOwnLine} is set to
		      $-1$.
	\end{itemize}
	The indentation is done in Phase 2; in Phase 3 \emph{there is no option to add a line
		break after the \lstinline!end! statements}. We can justify this by remembering that
	during Phase 3, the \texttt{one} environment will be found and processed first, followed
	by the \texttt{two} environment. If the \texttt{two} environment were to add a line break
	after the
	\lstinline!\end{two}! statement, then \texttt{latexindent.pl} would have no way of
	knowing how much indentation to add to the subsequent text (in this case,
	\lstinline!\end{one}!).

	We can explore this further using the poly-switches in \cref{lst:nested-env-mlb2}; upon
	running the command
	\index{switches!-l demonstration}
	\index{switches!-m demonstration}
	\begin{commandshell}
latexindent.pl -m -l=nested-env-mlb2.yaml nested-env.tex
\end{commandshell}
	we obtain the output given in \cref{lst:nested-env-mlb2-output}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/nested-env-mlb2.tex}{\texttt{nested-env.tex} using \cref{lst:nested-env-mlb2}}{lst:nested-env-mlb2-output}
		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/nested-env-mlb2.yaml}[MLB-TCB,width=\linewidth]{\texttt{nested-env-mlb2.yaml}}{lst:nested-env-mlb2}
	\end{cmhtcbraster}

	During Phase 1:
	\begin{itemize}
		\item the \texttt{two} environment is found first, and the line break ahead of the
		      \lstinline!\end{two}! statement is not changed because \texttt{EndStartsOnOwnLine} is
		      set to $1$. Importantly, because, \emph{at this stage},
		      \lstinline!\end{two}! \emph{does} finish with a line break,
		      \texttt{EndFinishesWithLineBreak} causes no action.
		\item next, the \texttt{one} environment is found; the line break ahead of
		      \lstinline!\end{one}! is already present, and no action is needed.
	\end{itemize}
	The indentation is done in Phase 2, and then in Phase 3, the \texttt{one} environment is
	found and processed first, followed by the \texttt{two} environment. \emph{At this
		stage}, the \texttt{two} environment finds \texttt{EndFinishesWithLineBreak} is $-1$, so
	it removes the trailing line break; remember, at this point, \texttt{latexindent.pl} has
	completely finished with the \texttt{one} environment.
